Explain how to fix reusable workflow errors - #384

Why

A reusable workflow input such as:

with:
  target: prefix-${{ needs.prepare.outputs.target }}

currently suggests a needs output reference without saying that it must be the whole value of a string input. Remote secret forwarding, unreadable public workflows, and expression-valued uses similarly state constraints without naming the affected workflow or showing a supported alternative.

What

Make these reusable-workflow errors explain the next valid step:

• Show the exact whole-value needs form and retain the distinct missing-needs and pre-job-value guidance.
• Name remote workflows, state that no secrets were forwarded, and suggest job-level buildkite-agent secret get NAME calls or equivalent local calls. Local secrets: inherit and explicit maps remain supported.
• Give the same non-enumerating private-or-absent guidance for an unavailable repository or missing public workflow path.
• Replace “runtime-dependent” with literal local and public uses examples.

Closes PB-3041
Closes PB-3026
Closes PB-3016
Closes PB-3017

Preview

Needs expression input

Workflow could not be run

.github/workflows/caller.yml

Reusable workflow input "target" uses a needs expression in an unsupported form.

.github/workflows/caller.yml:14:15 · Job call

Pass the whole value as exactly ${{ needs.<job>.outputs.<name> }}, with nothing around it.

Only string inputs can take a needs value, and Buildkite resolves it before the called job runs, so the reference has to be the entire value rather than part of a larger expression.

If you need a computed input from job outputs, log an issue on github.com/buildkite/buildkite-gha so we can prioritise it.

Remote secrets: inherit

Workflow could not be run

.github/workflows/caller.yml

secrets: inherit cannot forward secrets to a workflow in another repository.

.github/workflows/caller.yml:4:11 · Job call

Reusable workflow "owner/workflows/.github/workflows/ci.yml@v1" is outside this repository, so no secrets were forwarded.

Retrieve each secret by name with buildkite-agent secret get NAME in the jobs of that workflow, or copy the workflow into this repository's .github/workflows and use secrets: inherit with a ./ call.

If you need secrets: inherit across repositories, log an issue on github.com/buildkite/buildkite-gha so we can prioritise it.

Remote secrets: map

Workflow could not be run

.github/workflows/caller.yml

A secrets: map cannot forward secrets to a workflow in another repository.

.github/workflows/caller.yml:4:11 · Job call

Reusable workflow "owner/workflows/.github/workflows/ci.yml@v1" is outside this repository, so no secrets were forwarded.

Retrieve each secret by name with buildkite-agent secret get NAME in the jobs of that workflow, or copy the workflow into this repository's .github/workflows and use a secrets: map with a ./ call.

If you need explicit secret mappings across repositories, log an issue on github.com/buildkite/buildkite-gha so we can prioritise it.

Unavailable public workflow

Workflow could not be run

.github/workflows/private.yml

Reusable workflow could not be read.

.github/workflows/private.yml:4:11 · Job call

"owner/private/.github/workflows/ci.yml@v1" is either private or does not exist.

Only public workflows can be called across repositories.

Check the path, or copy the workflow into this repository's .github/workflows and call it with a ./ path.

If you need private cross-repository calls, log an issue on github.com/buildkite/buildkite-gha so we can prioritise it.

Expression-valued workflow path

Workflow could not be run

.github/workflows/dynamic.yml

Reusable workflow path cannot be an expression.

.github/workflows/dynamic.yml:4:11 · Job call

"${{ inputs.workflow }}" is only known once the build is running, and the workflow file has to be read before that.

Name the file directly, for example ./.github/workflows/ci.yml, or org/shared/.github/workflows/ci.yml@v1.

If you need a computed workflow path, log an issue on github.com/buildkite/buildkite-gha so we can prioritise it.